home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 2010 April / PCWorld0410.iso / hity wydania / Ubuntu 9.10 PL / karmelkowy-koliberek-desktop-9.10-i386-PL.iso / casper / filesystem.squashfs / usr / lib / perl5 / Gtk2 / Helper.pm < prev    next >
Encoding:
Perl POD Document  |  2009-05-17  |  5.3 KB  |  211 lines
  1. #
  2. # $Id$
  3. #
  4.  
  5. package Gtk2::Helper;
  6.  
  7. our $VERSION = '0.02';
  8.  
  9. use Carp;
  10. use strict;
  11.  
  12. use Glib;
  13.  
  14. sub add_watch {
  15.     shift; # lose the class
  16.     my ($fd, $cond, $callback, $data) = @_;
  17.  
  18.     # map 'in' and 'out' to GIO enums
  19.     $cond = $cond eq 'in'  ? 'G_IO_IN'  :
  20.         $cond eq 'out' ? 'G_IO_OUT' :
  21.         croak "Invalid condition flag. Expecting: 'in' / 'out'";
  22.  
  23.     # In Gtk 1.x the callback was called also for the eof() / pipe close
  24.     # events, but Gtk 2.x doesn't. We need to connect to the G_IO_HUP
  25.     # event also to get this convenient behaviour again.
  26.  
  27.     my $tag = {
  28.         io_id  => Glib::IO->add_watch ($fd, $cond, $callback, $data),
  29.         hup_id => Glib::IO->add_watch ($fd, 'G_IO_HUP', $callback, $data),
  30.     };
  31.  
  32.     return $tag;
  33. }
  34.  
  35. sub remove_watch {
  36.     shift; # lose the class
  37.     my ($tag) = @_;
  38.  
  39.     my $rc_io  = Glib::Source->remove ($tag->{io_id});
  40.     my $rc_hup = Glib::Source->remove ($tag->{hup_id});
  41.     
  42.     return ($rc_io && $rc_hup);
  43. }
  44.  
  45. 1;
  46.  
  47. __END__
  48.  
  49. =head1 NAME
  50.  
  51. Gtk2::Helper - Convenience functions for the Gtk2 module
  52.  
  53. =head1 SYNOPSIS
  54.  
  55.   use Gtk2::Helper;
  56.  
  57.   # Handle I/O watchers easily, like Gtk 1.x did
  58.   $tag = Gtk2::Helper->add_watch ( $fd, $cond, $callback, $data )
  59.   $rc  = Gtk2::Helper->remove_watch ( $tag )
  60.  
  61. =head1 ABSTRACT
  62.  
  63. This module collects Gtk2 helper functions, which should make
  64. implementing some common tasks easier.
  65.  
  66. =head1 DESCRIPTION
  67.  
  68. =head2 Gtk2::Helper->add_watch ( ... )
  69.  
  70.   $tag = Gtk2::Helper->add_watch ( $fd, $cond, $callback, $data )
  71.  
  72. This method is a wrapper for Glib::IO->add_watch. The callback is
  73. called every time when it's safe to read from or write to the
  74. watched filehandle.
  75.  
  76. =over 4
  77.  
  78. =item $fd
  79.  
  80. Unix file descriptor to be watched. If you use the FileHandle
  81. module you get this value from the FileHandle->fileno() method.
  82.  
  83. =item $cond
  84.  
  85. May be either 'in' or 'out', depending if you want to read from
  86. the filehandle ('in') or write to it ('out').
  87.  
  88. =item $callback
  89.  
  90. A subroutine reference or closure, which is called, if you can safely
  91. operate on the filehandle, without the risk of blocking your application,
  92. because the filehandle is not ready for reading resp. writing.
  93.  
  94. But aware: you should not use Perl's builtin read and write functions here
  95. because these operate always with buffered I/O. Use low level sysread() and
  96. syswrite() instead. Otherwise Perl may read more data into its internal
  97. buffer as your callback actually consumes. But Glib won't call the callback
  98. on data which is already in Perl's buffer, only when events on the
  99. the underlying Unix file descriptor occur.
  100.  
  101. The callback subroutine should return always true. Two signal
  102. watchers are connected internally (the I/O watcher, and a HUP
  103. watcher, which is called on eof() or other exceptions). Returning
  104. false from a watcher callback, removes the correspondent watcher
  105. automatically. Because we have two watchers internally, only one
  106. of them is removed, but probably not both. So always return true
  107. and use Gtk2::Helper->remove_watch to disable a watcher, which was
  108. installed with Gtk2::Helper->add_watch.
  109.  
  110. (Gtk2::Helper could circumvent this by wrapping your callback
  111. with a closure returning always true. But why adding another level
  112. of indirection if writing a simple "1;" at the end of your callback
  113. solves this problem? ;)
  114.  
  115. =item $data
  116.  
  117. This data is passed to the callback.
  118.  
  119. =item $tag
  120.  
  121. The method returns a tag which represents the created watcher.
  122. Later you need to pass this tag to Gtk2::Helper->remove_watch to
  123. remove the watcher.
  124.  
  125. =back
  126.  
  127. B<Example:>
  128.  
  129.   # open a pipe to a ls command
  130.   use FileHandle;
  131.   my $fh = FileHandle->new;
  132.   open ($fh, "ls -l |") or die "can't fork";
  133.  
  134.   # install a read watcher for this pipe
  135.   my $tag;
  136.   $tag = Gtk2::Helper->add_watch ( $fh->fileno, 'in', sub {
  137.     watcher_callback( $fh, $tag );
  138.   });
  139.  
  140.   sub watcher_callback {
  141.       my ($fh, $tag) = @_;
  142.  
  143.       # we safely can read a chunk into $buffer
  144.       my $buffer;
  145.  
  146.       if ( not sysread($fh, $buffer, 4096) ) {
  147.         # obviously the connected pipe was closed
  148.         Gtk2::Helper->remove_watch ($tag)
  149.         or die "couldn't remove watcher";
  150.     close($fh);
  151.     return 1;
  152.       }
  153.  
  154.       # do something with $buffer ...
  155.       print $buffer;
  156.  
  157.       # *always* return true
  158.       return 1;
  159.   }
  160.  
  161. =head2 Gtk2::Helper->remove_watch ( ... )
  162.  
  163.   $rc = Gtk2::Helper->remove_watch ( $tag )
  164.  
  165. This method removes a watcher, which was created using
  166. Gtk2::Helper->add_watch().
  167.  
  168. =over 4
  169.  
  170. =item $tag
  171.  
  172. This is the tag returned from Gtk2::Helper->add_watch().
  173.  
  174. =item $rc
  175.  
  176. The method returns true, if the watcher could be removed
  177. successfully, and false if not.
  178.  
  179. =back
  180.  
  181. =head1 SEE ALSO
  182.  
  183. perl(1), Gtk2(1)
  184.  
  185. =head1 AUTHOR
  186.  
  187. =encoding utf8
  188.  
  189. J├╢rn Reder E<lt>joern AT zyn.deE<gt>
  190.  
  191. =head1 COPYRIGHT AND LICENSE
  192.  
  193. Copyright 2003 by J├╢rn Reder
  194.  
  195. This library is free software; you can redistribute it and/or
  196. modify it under the terms of the GNU Library General Public
  197. License as published by the Free Software Foundation; either
  198. version 2.1 of the License, or (at your option) any later version.
  199.  
  200. This library is distributed in the hope that it will be useful,
  201. but WITHOUT ANY WARRANTY; without even the implied warranty of
  202. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  203. Library General Public License for more details.
  204.  
  205. You should have received a copy of the GNU Library General Public
  206. License along with this library; if not, write to the 
  207. Free Software Foundation, Inc., 59 Temple Place - Suite 330, 
  208. Boston, MA  02111-1307  USA.
  209.  
  210. =cut
  211.